home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / binfile.zip / BINFILE.DOC < prev    next >
Text File  |  1993-03-16  |  18KB  |  451 lines
  1.                       Binary File Unit For Turbo Pascal 6.0
  2.  
  3.                          Program Name : BinFile.Pas
  4.                          Written By Donald S. P. Golding, Jr.
  5.                          Date         : March 13, 1993
  6.                          Version      : 1.0
  7.  
  8.  
  9. This program may be freely distributed for non-commercial, non-business,
  10. and non-governmental uses, provided this notice is attached with it.  This
  11. program is copyrighted by Donald Golding Jr.  If you find any use for it
  12. please register it with me. Additionally, let me know of any useful programs
  13. that you develop with this program unit via my address.
  14.  
  15.           Home Address : 114 South 8th Avenue
  16.                          Mount Vernon, N.Y. 10550
  17.                          U.S.A.
  18.  
  19. The compiled version of BINFILE.TPU was compiled in TURBO PASCAL 6.0.  If you want
  20. a unit file for Turbo Pascal 5.5 or Turbo Pascal 1.5 for windows please contact me. 
  21. These TPU's will be included at a later date.
  22.  
  23. Introduction
  24. ------------
  25. This unit provides the user with an object called BinaryFileObj.  This object
  26. allows the user to read, write, sort and do various operations on a data file. 
  27. There are many other types in the unit that are used to aid the object.  The
  28. following is an example program using the BinaryFileObj.
  29.  
  30. Program Filetst ;
  31.  
  32. Uses Crt, Dos, BinFile;
  33.  
  34. {$F+}
  35. Function NameSort (Index1, Index2 : LongInt; Var Data1, Data2) : CompareType ;
  36.  
  37.    Begin
  38.  
  39.       If SearchRec(Data1).Name > SearchRec(Data2).Name Then
  40.  
  41.          NameSort := CompGreater
  42.  
  43.       Else If SearchRec(Data1).Name < SearchRec(Data2).Name Then
  44.  
  45.               NameSort := CompLess
  46.  
  47.            Else NameSort := CompEqual ;
  48.  
  49.    End ;
  50. {$F-}
  51.  
  52. {$F+}
  53. Function Search1 (FileOffSet : LongInt; Var DataToFind, DataRead) : Boolean ;
  54.  
  55.    Begin
  56.  
  57.       Search1 := SearchRec(DataToFind).Name = SearchRec(DataRead).Name ;
  58.  
  59.    End ;
  60. {$F-}
  61.  
  62. {$F+}
  63. Function Search2 (FileOffSet : LongInt; Var DataToFind, DataRead) : CompareType ;
  64.  
  65.    Begin
  66.  
  67.       If SearchRec(DataToFind).Name > SearchRec(DataRead).Name Then
  68.  
  69.          Search2 := CompGreater
  70.  
  71.       Else If SearchRec(DataToFind).Name < SearchRec(DataRead).Name Then
  72.  
  73.               Search2 := CompLess
  74.  
  75.            Else Search2 := CompEqual ;
  76.  
  77.    End ;
  78. {$F-}
  79.  
  80. Var
  81.  
  82.    TestFile : BinaryFileObj ;
  83.    SRec     : SearchRec     ;
  84.    Count    : LongInt       ;
  85.    SUC      : Boolean       ;
  86.    OffS     : LongInt       ;
  87.    TempChar : Char          ;
  88.  
  89. Begin
  90.  
  91.    TestFile.Init ('FileName.Dat', True, SizeOf(SearchRec)) ;
  92.  
  93.    Writeln ('Reading Files ....') ;
  94.    FindFirst ('*.*',AnyFile,SRec) ;
  95.  
  96.    While (DosError = 0) And (TestFile.GetError = NoError) Do
  97.  
  98.       Begin
  99.  
  100.          TestFile.WriteData (NextWrite, SizeOf(SearchRec), SRec, Suc) ;
  101.          FindNext (SRec) ;
  102.  
  103.       End ;
  104.  
  105.    Writeln ('Sorting File .....') ;
  106.    TestFile.QuickSort (Ascending, SizeOf(SearchRec), NameSort, DefaultStartOffSet,
  107.                        DefaultEndOffSet, Suc) ;
  108.    Writeln ('Sort SuccessFul : ',Suc) ;
  109.  
  110.    TempChar := ReadKey ;
  111.    TestFile.ResetFile ;
  112.  
  113.    Count := 0 ;
  114.    While (Not TestFile.GetEof) And (TestFile.GetError = NoError) Do
  115.  
  116.       Begin
  117.  
  118.          Inc (Count) ;
  119.          TestFile.ReadData (NextRead, SizeOf(SearchRec), SRec, Suc) ;
  120.          Writeln (Count, '. File Name : ',SRec.Name) ;
  121.          If Count Mod 10 = 0 Then
  122.  
  123.             TempChar := ReadKey ;
  124.  
  125.       End ;
  126.  
  127.    TempChar := Readkey ;
  128.  
  129.    SRec.Name := '..' ;
  130.    TestFile.LinearSearch (Search1, SizeOf(SearchRec), SRec,
  131.                           DefaultStartOffSet, Offs, Suc) ;
  132.    Writeln (Suc, ' ', Offs) ;
  133.    TempChar := ReadKey ;
  134.  
  135.    If Suc Then
  136.  
  137.       Begin
  138.  
  139.          TestFile.ReadData (OffS, SizeOf(SearchRec),SRec, Suc) ;
  140.          Writeln (Suc, ' ',SRec.Name) ;
  141.          TempChar := ReadKey;
  142.  
  143.       End ;
  144.  
  145.    SRec.Name := '..' ;
  146.    TestFile.BinarySearch (Search2, Ascending, SizeOf(SRec), SRec,
  147.                           DefaultOffSetFactor, OffS, Suc) ;
  148.    Writeln (Suc, ' ', Offs) ;
  149.    TempChar := Readkey ;
  150.  
  151.    If Suc Then
  152.  
  153.       Begin
  154.  
  155.          TestFile.ReadData (OffS, SizeOf(SearchRec), SRec, Suc) ;
  156.          Writeln (Suc, ' ',SRec.Name) ;
  157.          TempChar := ReadKey ;
  158.  
  159.       End ;
  160.  
  161.    TestFile.Done (True);
  162.  
  163. End.
  164.  
  165. -----------------------------------------------------------------------------
  166.  
  167.  
  168. Constants
  169. ---------
  170.  
  171. Constants available in BinFile unit.
  172.  
  173.    { Error constants }
  174.    NoError             =  0  ;
  175.    Err_FileNotFound    = -1  ;
  176.    Err_NoDiskSpace     = -2  ;
  177.    Err_InvalidOffSet   = -3  ;
  178.    Err_InvalidDataSize = -4  ;
  179.    Err_DriveNotReady   = -5  ;
  180.    Err_ReadError       = -6  ;
  181.    Err_NotEnoughSpace  = -7  ;
  182.    Err_FileNotOpen     = -8  ;
  183.    Err_NotEnoughMem    = -9  ;
  184.    Err_DiskIO          = -10 ;
  185.    Err_InvalidFileSize = -11 ;
  186.    Err_Unknown         = -50 ;
  187.  
  188.    { Processing Constants }
  189.    NextWrite           = -1  ;
  190.    NextRead            = -2  ;
  191.    DefaultStartOffSet  = -3  ;
  192.    DefaultEndOffSet    = -4  ;
  193.    DefaultOffSetFactor = -5  ;
  194.  
  195. -----------------------------------------------------------------------------
  196.  
  197.  
  198. Types
  199. -----
  200. Other types in BinFile unit.
  201.  
  202. -----------------------------------------------------------------------------
  203. OrderType = (Ascending, Descending) ;
  204.  
  205. Used for ordering sorts.
  206.  
  207. -----------------------------------------------------------------------------
  208. CompareType = (CompEqual, CompGreater, CompLess) ;
  209.  
  210. Used for comparison of data.
  211.  
  212. -----------------------------------------------------------------------------
  213. CompareFuncType = Function (OffSet1, OffSet2 : LongInt ;
  214.                             Var Data1, Data2) : CompareType ;
  215.  
  216. Declaration of the format of a user defined procedure for comparison.
  217.  
  218. -----------------------------------------------------------------------------
  219. SearchFuncTypeL = Function (FileOffSet : LongInt;
  220.                             Var DataToFind, DataRead) : Boolean ;
  221.  
  222. Declaration of the format of a user defined procedure for linear search.
  223.  
  224. -----------------------------------------------------------------------------
  225. SearchFuncTypeB = Function (FileOffSet : LongInt;
  226.                             Var DataToFind, DataRead) : CompareType ;
  227.  
  228. Declaration of the format of a user defined procedure for binary search.
  229.  
  230. -----------------------------------------------------------------------------
  231. BinaryFileObjPtr = ^BinaryFileObj ;
  232.  
  233. A pointer type to the binary file object.
  234.  
  235. -----------------------------------------------------------------------------
  236. PerformType      = Procedure (FileOffSet : LongInt; Var Data; DSize : Word;
  237.                               BinObjPtr : BinaryFileObjPtr) ;
  238.  
  239. Declaration format for the perform all procedure.
  240. -----------------------------------------------------------------------------
  241.  
  242.  
  243. Methods
  244. -------
  245. The methods for BinaryFileObj object are as follows
  246.  
  247. ----------------------------------------------------------------------------
  248. Constructor BinaryFileObj.Init (FileName : String; NewFile : Boolean;
  249.                                 DataS : Word) ;
  250.  
  251. Initializes the file object and must be called first.  FILENAME is the name
  252. of the file to be accessed by the object.  NEWFILE indicated whether or not
  253. the file should be considered a new file.  If the file already exists then
  254. the existing file's data is erased.  Otherwise the file is created.  DATAS
  255. is the size of data to be stored in the file. This number is used as the
  256. default data size if it is greater than 0.  If DATAS is 0 then the file's
  257. data will be retrieved dynamically.  Any access to data in the file (reading
  258. or writing) this data size will have to be indicated.
  259.  
  260. ----------------------------------------------------------------------------
  261. Destructor BinareFileObj.Done (FileErase : Boolean) ;
  262.  
  263. This object uninitialized all allocated memory and releases the file.  If
  264. FILEERASE is true then the file is erased.
  265.  
  266. ----------------------------------------------------------------------------
  267. Procedure BinaryFileObj.ReadData (FileOffSet : LongInt; DataS : Word;
  268.                                   Var Data; Var SuccessFul : Boolean) ;
  269.  
  270. This method allows you to read the data from the file.  FILEOFFSET is the
  271. offset into the file to start the read.  If FILEOFFSET is less than 0 then
  272. reading will start from the current file offset.  DATAS is the size of the
  273. data to be read.  If the data size that was indicated in the
  274. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  275. the size was not stated in the BinaryfileObj.Init method then this value is
  276. check.  If DATAS is 0 then an error will be indicated. DATA is the variable
  277. that will recieve the data that is read from the data file.  SUCCESSFUL is
  278. true is the read of the file was accomplished.
  279.  
  280. ----------------------------------------------------------------------------
  281. Procedure BinaryFileObj.WriteData (FileOffSet : LongInt; DataS : Word;
  282.                                    Var Data; Var SuccessFul : Boolean) ;
  283.  
  284. Same a ReadData except data is written.
  285.  
  286. ----------------------------------------------------------------------------
  287. Procedure BinaryFileObj.Copy (SrcOffSet, DestOffSet : LongInt; DataS : Word ;
  288.                               Var SuccessFul : Boolean) ;
  289.  
  290. Copies data from one file offset to another.  SRCOFFSET is the file offset
  291. for the source data to be copied.  DESTOFFSET is the destination file offset.
  292. DATAS is the size of the data.  If the data size that was indicated in the
  293. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  294. the size was not stated in the BinaryfileObj.Init method then this value is
  295. check.  If DATAS is 0 then an error will be indicated.  SUCCESSFUL is true
  296. if the copy was done correctly.
  297.  
  298. ----------------------------------------------------------------------------
  299. Procedure BinaryFileObj.Swap (OffSet1, OffSet2 : LongInt; DataS : Word ;
  300.                               Var SuccessFul : Boolean) ;
  301.  
  302. Swaps data from one file offset to another.  OFFSET1 is the first file offset.
  303. OFFSET2 is the second offset.  DATAS is the size of the data.  If the data
  304. size that was indicated in the BinaryFileObj.Init method was greater than 0
  305. then this value is ignored.  If the size was not stated in the
  306. BinaryfileObj.Init method then this value is check.  If DATAS is 0 then an
  307. error will be indicated. SUCCESSFUL is true if the swap was done correctly.
  308.  
  309. ----------------------------------------------------------------------------
  310. Procedure BinaryFileObj.BubbleSort (Order : OrderType; DataS : Word;
  311.                                     CompareFunc : CompareFuncType ;
  312.                                     StartOffS, EndOffS : LongInt ;
  313.                                     Var SuccessFul : Boolean) ;
  314.  
  315. Uses the Bubble Sort to sort the file.  ORDER is the order in which to sort
  316. the data file (Ascending or Descending).  DATAS is the size of the data.  If
  317. the data size that was indicated in the BinaryFileObj.Init method was greater
  318. than 0 then this value is ignored.  If the size was not stated in the
  319. BinaryfileObj.Init method then this value is check.  If DATAS is 0 then an
  320. error will be indicated.  COMPAREFUNC is the user defined function that is
  321. used to get a result of a comparison between data.  STARTOFFS is the starting
  322. offset in the file to start sorting.  If STARTOFFS is negative then the sort
  323. starts from the beginning of the file.  ENDOFFS is the ending offset to end
  324. the sort.  If ENDOFFS is negative then the ending offset is the last record
  325. in the data file. SUCCESSFUL is true if the sort was done correctly.
  326.  
  327. ----------------------------------------------------------------------------
  328. Procedure BinaryFileObj.QuickSort (Order : OrderType; DataS : Word;
  329.                                    CompareFunc : CompareFuncType ;
  330.                                    StartOffS, EndOffS : LongInt ;
  331.                                    Var SuccessFul : Boolean) ;
  332.  
  333. Uses the Quick Sort to sort the file.  (Faster than Bubble sort) ORDER is the
  334. order in which to sort the data file (Ascending or Descending).  DATAS is the
  335. size of the data.  If the data size that was indicated in the
  336. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  337. the size was not stated in the BinaryfileObj.Init method then this value is
  338. check.  If DATAS is 0 then an error will be indicated. COMPAREFUNC is the
  339. user defined function that is used to get a result of a comparison between
  340. data.  STARTOFFS is the starting offset in the file to start sorting.  If
  341. STARTOFFS is negative then the sort starts from the beginning of the file.
  342. ENDOFFS is the ending offset to end the sort.  If ENDOFFS is negative then
  343. the ending offset is the last record in the data file. SUCCESSFUL is true if
  344. the sort was done correctly.
  345.  
  346. ----------------------------------------------------------------------------
  347. Procedure BinaryFileObj.LinearSearch (SearchFunc : SearchFuncTypeL;
  348.                                       DataS : Word; Var DataToFind;
  349.                                       StartOffSet : LongInt ;
  350.                                       Var OffSet : LongInt ;
  351.                                       Var SuccessFul : Boolean) ;
  352.  
  353. Searches the file for the data in DATATOFIND variable.  SEARCHFUNC is the
  354. user defined function which returns true if the data was found.  DATAS is the
  355. size of the data.  If the data size that was indicated in the
  356. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  357. the size was not stated in the BinaryfileObj.Init method then this value is
  358. check.  If DATAS is 0 then an error will be indicated.  STARTOFFSET is the
  359. offset to start the search.  If negative then the search starts at the
  360. beginning of the file.  OFFSET will contain the file offset where the data was
  361. found.  If the data is not found then OFFSET equals -1.  SUCCESSFUL is true if
  362. the data was found.
  363.  
  364. ----------------------------------------------------------------------------
  365. Procedure BinaryFileObj.BinarySearch (SearchFunc : SearchFuncTypeB;
  366.                                       Order      : OrderType      ;
  367.                                       DataS : Word; Var DataToFind;
  368.                                       OffSetFactor : LongInt      ;
  369.                                       Var OffSet : LongInt ;
  370.                                       Var SuccessFul : Boolean) ;
  371.  
  372. Searches the file for the data in DATATOFIND variable.  SEARCHFUNC is the
  373. user defined function which returns true if the data was found.  The only way
  374. that the binary search will work successfully is if the data file has already
  375. been sorted. ORDER is the order in which the file was sorted.  DATAS is the
  376. size of the data.  If the data size that was indicated in the
  377. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  378. the size was not stated in the BinaryfileObj.Init method then this value is
  379. check.  If DATAS is 0 then an error will be indicated.  OFFSETFACTOR is the
  380. offset to start the search.  Any data below the OFFSETFACTOR will be ignored.
  381. If negative then the search starts at the beginning of the file. OFFSET will
  382. contain the file offset where the data was found.  If the data is not found
  383. then OFFSET equals -1.  SUCCESSFUL is true if the data was found.
  384.  
  385. ----------------------------------------------------------------------------
  386. Procedure BinaryFileObj.PerformForAll (StartOffSet : LongInt; DataS : Word;
  387.                                        UserProcedure : PerformType)
  388.  
  389. Calls the user defined procedure USERPROCEDURE and passed to that procedure
  390. the current data being accessed by the PERFORMFORALL method and the current
  391. offset.  Refer to the declaration of the PERFORMTYPE variable type.
  392. STARTOFFS is the offset in the file to start reading at.  If STARTOFFS is
  393. negative then this method starts at the beginning of the file.  DATAS is the
  394. size of the data. If the data size that was indicated in the
  395. BinaryFileObj.Init method was greater than 0 then this value is ignored.  If
  396. the size was not stated in the BinaryfileObj.Init method then this value is
  397. check.  If DATAS is 0 then an error will be indicated.
  398.  
  399. ----------------------------------------------------------------------------
  400. Procedure BinaryFileObj.ReduceFileSize (NewFileSize : LongInt;
  401.                                         Var SuccessFul : Boolean) ;
  402.  
  403. Reduces the size of a file to size NEWFILESIZE.  The value of NEWFILESIZE
  404. must be greater than or equal to 0.  SUCCESSFUL is true if the method
  405. completed the operation without error.
  406.  
  407. ----------------------------------------------------------------------------
  408. Procedure BinaryFileObj.ResetFile ;
  409.  
  410. Resets the file offsets to the beginning of the file.
  411.  
  412. ----------------------------------------------------------------------------
  413. Function BinaryFileObj.GetEof : Boolean ;
  414.  
  415. Indicates whether we are at the end of a file.
  416.  
  417. ----------------------------------------------------------------------------
  418. Function BinaryFileObj.GetFileSize : LongInt ;
  419.  
  420. Returns current file size.
  421.  
  422. ----------------------------------------------------------------------------
  423. Function BinaryFileObj.GetOffSet : LongInt ;
  424.  
  425. Returns current file offset.
  426.  
  427. ----------------------------------------------------------------------------
  428. Function BinaryFileObj.GetFileName : String ;
  429.  
  430. Returns file name.
  431.  
  432. ----------------------------------------------------------------------------
  433. Function BinaryFileObj.GetDataSize : Word ;
  434.  
  435. Returns default data size.
  436.  
  437. ----------------------------------------------------------------------------
  438. Function BinaryFileObj.GetFileOpen : Boolean ;
  439.  
  440. Returns if file is open.
  441.  
  442. ----------------------------------------------------------------------------
  443. Function BinaryFileObj.GetError : Integer ;
  444.  
  445. Returns current error code.
  446.  
  447. ----------------------------------------------------------------------------
  448. Procedure BinaryFileObj.ClearError ;
  449.  
  450. Sets the error code to NOERROR.
  451.